home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / boi120p.zip / BOI120.DOC < prev    next >
Text File  |  1991-01-29  |  19KB  |  473 lines
  1. BOI Reference Manual 1.20  12/15/90
  2.  
  3.  
  4.     BBS Onliner Interface 1.20
  5.     (C) 1990 Andrew J. Mead
  6.     All Rights Reserved.
  7.  
  8.     Contact:
  9.     POB 1155
  10.     Chapel Hill, NC 27514-1155
  11.           or
  12.     1:151/223.36 FidoNet
  13.     #98@9968 WWIVnet
  14.  
  15.     Turbo Pascal and TP are registered trademarks of Borland International.
  16.     Quick Basic and QB are registered trademarks MicroSoft Incorporated.
  17.  
  18.  
  19.     Sections in order of Appearance
  20.       Initial Statement
  21.       ShareWare Liscense Agreement
  22.       Registration Cost
  23.       Technical Support
  24.       Registration Agreement
  25.       UNIT BIODECL
  26.       UNIT GETCMBBS
  27.       UNIT IOLIB
  28.       UNIT ASYNC
  29.       UNIT IOSUPP
  30.       UNIT SUPPORT
  31.       BOI Documentation Files
  32.       Future Enhancements
  33.       Implementation Discussion
  34.  
  35.  
  36.     Initial Statement
  37.       I would like to see the command line switches used by this interface
  38.       become a standard for BBS online doors.  Since the BBS programmers
  39.       are not creating a standard drop file very quickly, we door programmers
  40.       will need to make do.  If you are not a Turbo Pascal programmer, I
  41.       still ask that you consider implementing my command line switching
  42.       system.
  43.  
  44.       The UNIT sections of this document detail the functionality of each
  45.       procedure and function contained in each unit.  Unit BIODECL is
  46.       pretty much self explanatory, and looking at it directly is the
  47.       best way to get information on it.
  48.  
  49.  
  50.     ShareWare Liscence Agreement
  51.       This package is ShareWare.  If you use this package, please send me
  52.       money.  Feel free to use the ideas and code from this package, but
  53.       if you use the interface itself to any extent, place the following
  54.       on the opening or copyright screen.
  55.  
  56.       BBS Onliner Interface version 1.20
  57.       (C) 1990 Andrew J. Mead
  58.       All Rights Reserved.
  59.       Contact: POB 1155 Chapel Hill, NC 27514-1155
  60.  
  61.       If you alter the code, put your revision number AFTER the '1.20'
  62.       ie (version 1.20 revision 1.0).  I will maintain, and steadily
  63.       update the interface.  If you have any ideas, suggestions, or
  64.       improvements, please send them to me.  There is plenty of room for
  65.       improvement in the interface.
  66.  
  67.  
  68.     Registration Costs
  69.       The registration fee for the BOI is $35.00 U.S.  There will be a
  70.       Turbo C version of the interface available in 1991.  See BOIREG.DOC
  71.       for registration form.
  72.  
  73.  
  74.     Technical Support
  75.       I am always willing to offer support.  I can be reached at #98@9968
  76.       on the WWIVnet and 1:151/223.36 on the FidoNet.  A support conference
  77.       on both systems may become available if demanded.  Please be specific
  78.       with your questions, and include any details you have.  If someone
  79.       out there would like to help with the technical support, let me know.
  80.  
  81.  
  82.     UNIT BIODECL
  83.       See BIODECL.PAS for documentation.  This Unit is merely a
  84.       clearing house for public variables and constants.  This is used
  85.       by every other unit and the door program itself.
  86.  
  87.     UNIT GETCMBBS
  88.  
  89.       Uses
  90.         Dos
  91.         BOIDecl
  92.  
  93.       Procedure
  94.         GetCommand
  95.  
  96.       Procedure GETCOMMAND(infofile, inhof, logfile : pathstr;
  97.           gamename, version : string;  programset : charset);
  98.  
  99.         infofile   - name of the doors documentation file.
  100.         inhof      - default name for text hall of fame (can be '').
  101.         logfile    - name of error log.
  102.         gamename   - name of the door.
  103.         version    - door version number (string).
  104.         programset - set of door defined command line arguments.  Must
  105.             be in ['+','-','=','[',']','.'].  These arguments are to
  106.             be processed by the door itself.
  107.  
  108.         GetCommand is the front-end of the interface.  it reads the
  109.         BBS dropfile, and initializes the communications settings.
  110.  
  111.  
  112.     UNIT IOLIB
  113.  
  114.       Uses
  115.         Dos
  116.  
  117.       Functions
  118.         Exist                     GetTimer                  IntStr
  119.         KeyPressed                LeftTime                  Max
  120.         Min                       PadStr                    PortKeyPressed
  121.         ReadKey                   ReadPortKey               RealStr
  122.         Valid                     WhereX                    WhereY
  123.  
  124.       Procedures
  125.         ClearBuffers              ClrPortEol                ClrPortScr
  126.         Delay                     DoTimeOut                 EndPort
  127.         GetString                 GotoPortXY                PortBackground
  128.         PortColor                 PortColumnOne             PortWindow
  129.         ResetPortXY               SendString                SetPort
  130.         SetPortXY                 TextPortColor             TimerSet
  131.  
  132.       Procedure CLEARBUFFERS
  133.         ClearBuffers empties both the host keyboard and the port input
  134.         buffers.  This procedure is helpful in controlling 'Type-ahead'
  135.         problems.  With a 1k port input buffer, the remote user could
  136.         inadvertently lean on a key putting hundreds of key-strokes into
  137.         the buffer.
  138.  
  139.       Procedure CLRPORTSCR                                  ANSI
  140.         ClearPortScr sends the ANSI code to clear the defined screen
  141.         window (PortWindow).  If there is a remote user, the current
  142.         status line will be written on line 25 on the host screen.
  143.         This replaces TPs CRT ClrScr.
  144.  
  145.       Procedure CLRPORTEOL                                  ANSI
  146.         ClearPortEol sends the ANSI code to clear the current line from
  147.         the current cursor position to the right edge of the screen.
  148.  
  149.       Procedure DELAY(ms : Word)                            BIOS
  150.         This procedure is identical to the one in TPs CRT Unit.  ms
  151.         is the approxiamate time of CPU delay in milliseconds (993 per
  152.         second).
  153.  
  154.       Procedure DOTIMEOUT(ringbell : boolean)
  155.         This procedure is called upon modem or user inactivity time-out.
  156.         There should be no reason for the door itself to call this procedure.
  157.         ringbell tells it to echo a bell to the remote user (if communications
  158.         still exist).
  159.  
  160.       Procedure ENDPORT
  161.         EndPort should be the last line of your door program.  This procedure
  162.         disables the BIO Async routines, and restores the previously
  163.         installed routines.  This procedure should be called before
  164.         the program ends, especially during abnormal termination, so that
  165.         the BBSs communication routines are re-established.  See SetPort.
  166.  
  167.       Function EXIST(thisfile : pathstr) : boolean
  168.         Exists tells whether or not ThisFile exists or not.  Should be used
  169.         in conjunction with Valid.  This is a public domain function.
  170.  
  171.       Procedure GETSTRING(var gstr : string)
  172.         GetString returns all characters input locally and from remote upto
  173.         the next carriage return.  This is a 'dumb' procedure, and will not
  174.         reject any characters.  See ReadKey and ReadPortKey.
  175.  
  176.       Function GETTIMER(var basetime : longint; val : word) : boolean
  177.         basetime - clockticks since midnight (18.2 per second)
  178.         val      - number of seconds
  179.  
  180.         GetTimer returns true if val seconds have passed since basetime.
  181.         You must use SetTimer to initialize basetime.  These two procedures
  182.         can be used for many purposes including benchmarks and user
  183.         inactivity timeouts.  See SetTimer.
  184.  
  185.       Procedure GOTOPORTXY(x,y : byte)                      ANSI
  186.         GotoPortXY uses ANSI codes to position the cursor.  Replaces
  187.         TPs CRT GotoXY.
  188.  
  189.       Function INTSTR(val : longint; isize : byte) : string
  190.         val   - ennumerated value to convert to a string
  191.         isize - size of string
  192.  
  193.         IntStr returns a string of an integer value.  Best utilized by
  194.         SendString for formatted (left or right justified) output.
  195.         See SendString, PadStr, RealStr.
  196.  
  197.       Function KEYPRESSED : Boolean
  198.         KeyPressed replaces TPs CRT KeyPressed.  It returns true if
  199.         there is a key waiting in the local keyboard buffer.  You should
  200.         use PortKeyPressed for general use.
  201.  
  202.       Function LEFTTIME : integer
  203.         LeftTime returns the users current time remaining in minutes.
  204.  
  205.       Function MAX (a,b : word) : word
  206.         Max returns the greater of a and b.
  207.  
  208.       Function MIN (a,b : word) : word
  209.         Min returns the lesser of a and b.
  210.  
  211.       Function PADSTR(pstr : string; psize : byte) : string
  212.         pstr  - input string
  213.         psize - size of string
  214.  
  215.         PadStr returns a right-justified string.  (pstr right-justified
  216.         to psize characters).  PadStr should be used with SendString for
  217.         formatted output.  See SendString, IntStr, RealStr.
  218.  
  219.       Procedure PORTBACKGROUND(color: byte)                 ANSI
  220.         PortBackground sends the ANSI color codes to change the background
  221.         color.  Use the predefined color constants for this command.
  222.         This procedure replaces TPs CRT TextBackground.  See PortColor.
  223.  
  224.       Procedure PORTCOLOR(acolor, bcolor : byte)            ANSI
  225.         PortColor allows for color/monochrome screen control.  If
  226.         DoColor (See Unit BOIDecl) is true then acolor is the foreground
  227.         color, otherwise bcolor is the foreground color.  bcolor should
  228.         only be lightgray or white (with or without blink).
  229.         See TextPortColor, PortBackground.
  230.  
  231.       Procedure PORTCOLUMNONE                               ANSI
  232.         This procedure places the current at the left edge of the screen.
  233.         Same as GotoXY(1,WhereX) using TPs CRT.  See ResetPortXY, SetPortXY,
  234.         WhereX, WhereY.
  235.  
  236.       Function PORTKEYPRESSED
  237.         This procedure replaces the KeyPressed routine from TPs CRT.
  238.         See KeyPressed, ReadPortKey, ReadKey.
  239.  
  240.       Procedure PORTWINDOW(x1,y1,x2,y2 : byte)
  241.         Replaces TPs CRT Window(x1,y1,x2,y2).  Not as complete.  This
  242.         procedure will be upgraded greatly in the future.
  243.  
  244.       Function READKEY : char                               BIOS
  245.         Reads next character from local keyboard buffer.  This replaces
  246.         TPs CRT ReadKey.  See ReadPortKey,  CheckSecondKey (Unit IOSUPP).
  247.  
  248.       Function READPORTKEY : char
  249.         ReadPortKey returns the next waiting character from either the
  250.         local keyboard buffer or the port input buffer.  This should
  251.         be used instead of ReadKey.  This behave like TPs ReadKey except
  252.         that extended codes are not pushed into the input buffer.  They
  253.         are processed by CheckSecondKey (See Unit IOSupp).  This function
  254.         should only be called when the program is ready to wait for user
  255.         input (it will timeout after 2 minutes), or the program knows a
  256.         key is waiting (PortKeyPressed = true).
  257.         See ReadKey, PortKeyPressed.
  258.  
  259.       Function REALSTR(rval : real; rsize, rdec  : byte) : string
  260.         rval  - ennumerated value to convert to a string
  261.         rsize - size of string
  262.         rdec  - number of decimal places in string
  263.  
  264.         RealStr returns a string of a real value.  Best utilized by
  265.         SendString for formatted (left or right justified) output.
  266.         See SendString, IntStr, PadStr.
  267.  
  268.       Procedure RESETPORTXY                                 ANSI
  269.         ResetPortXY uses ANSI control codes to place the cursor at
  270.         the position stored by the most recent call to SetPortXY.
  271.  
  272.       Procedure SENDSTRING(outstr : string; docr : boolean)
  273.         outstr - string to be output
  274.         docr   - send carriage return / linefeed
  275.  
  276.         SendString is the main output function.  Senstring replaces
  277.         TPs Write and Writeln (for non-file) output procedures.
  278.         See IntStr, PadStr, RealStr.
  279.  
  280.       Procedure SETPORT                { Initialize Async Communications }
  281.         SetPort initializes the BOI communications.  This procedure should
  282.         be the one used to enable the Async routines.  See EndPort.
  283.  
  284.       Procedure SETPORTXY                                   ANSI
  285.         SetPortXY uses ANSI control codes to store the current cursor
  286.         position, so that it can be restored after some other activity
  287.         (by ResetPortXY).  You should use this procedure in your online
  288.         doors instead of using the methodology of (GotoXY, WhereX, etc.).
  289.         See ResetPortXY.
  290.  
  291.       Procedure TEXTPORTCOLOR(color : byte)   { set text attributes }
  292.         TextPortColor replaces TPs CRT TextColor procedure.  It uses
  293.         ANSI commands to set the foreground color.  A better version of
  294.         this procedure is PortColor.  See PortColor, PortBackground.
  295.  
  296.       Procedure TIMERSET(var basetime : longint)
  297.         TimerSet initializes basetime.  It sets basetime to the number
  298.         of CPU clock ticks since midnight (18.2 per second).
  299.         See GetTimer.
  300.  
  301.       Function VALID(thisfile : pathstr) : boolean;
  302.         Valid tells whether or not ThisFile is a valid Dos filename
  303.         exists or not.  Should be used in conjunction with Exist.
  304.         This is a public domain function.
  305.  
  306.       Function WHEREX : byte                                BIOS
  307.         Replaces TPs CRT WhereX.  This procedure should not be used.
  308.         You should restructure your programs to use SetPortXY and
  309.         ResetPortXY.  See WhereY.
  310.  
  311.       Function WHEREY : byte                                BIOS
  312.         Replaces TPs CRT WhereY.  This procedure should not be used.
  313.         You should restructure your programs to use SetPortXY and
  314.         ResetPortXY.  See WhereX.
  315.  
  316.  
  317.     UNIT ASYNC
  318.  
  319.       Functions
  320.         Carrier
  321.         CharReady
  322.         ReadBuffer
  323.  
  324.       Procedures
  325.         AsyncInt                  ClearInBuffer             DropCarrier
  326.         IntEnd                    IntInit                   SendChar
  327.         SetBufferSize
  328.  
  329.       Procedure ASYNCINT : Interrupt                        IRQ
  330.         This is the engine of the communications routine.  This
  331.         procedure should never be called directly.
  332.         See IntInit and IntEnd.
  333.  
  334.       Function CARRIER : boolean
  335.         Carrier returns true if carrier is detected, dolocal is true,
  336.         or carrier detect override is in effect.
  337.  
  338.       Function CHARREADY : char
  339.         CharReady returns true if the port input buffer is not empty.
  340.         See ReadBuffer.
  341.  
  342.       Procedure DROPCARRIER
  343.         DropCarrier will tell the modem to hang up the phone.  This
  344.         procedure should be used with extreme prejudice.
  345.  
  346.       Procedure INTEND
  347.         IntEnd disengages AsyncInt and restores the previous communications
  348.         interrupt.  This procedure should not be called directly.  You
  349.         should use EndPort (See Unit IOLIB).
  350.         See IntInit, AsyncInt.
  351.  
  352.       Procedure INTINIT
  353.         IntInit installs AsyncInt as the current communications interrupt
  354.         handler.  This procedure should not be called directly.  You
  355.         should use SetPort (See Unit IOLIB).
  356.         See IntEnd, AsyncInt, SetBufferSize.
  357.  
  358.       Function READBUFFER : char
  359.         ReadBuffer returns the next character in the input buffer.  This
  360.         should only be called after CharReady returns true.
  361.  
  362.       Procedure SENDCHAR(outchar : char)
  363.         SendChar sends outchar to the communications port.  This procedure
  364.         should not be called directly.  See SendString (Unit IOLIB).
  365.  
  366.       Procedure SETBUFFERSIZE(newsize : integer)
  367.         Changes size of circular input buffer.  Default is 1024 characters.
  368.         This command will also clear the buffer.
  369.  
  370.  
  371.     UNIT IOSUPP
  372.  
  373.       Procedure
  374.         CheckSecondKey
  375.  
  376.       Procedure CHECKSECONDKEY(var cskey : char)
  377.         CheckSecondKey is used to interpret extended character codes
  378.         returned by the local keyboard.  If the code is not processed,
  379.         $00 is returned.  F-9, and F-10 have default values.  You could
  380.         use this structure to implement more SysOp functions such as
  381.         ChatMode, add or subtract user time, etc...  This procedure
  382.         is used only by ReadPortKey (see UNIT IOLIB).
  383.  
  384.  
  385.     UNIT SUPPORT
  386.  
  387.       Var
  388.         playerpoints : longint
  389.  
  390.       Function
  391.         WriteCopy
  392.  
  393.       Procedures
  394.         AbortGame
  395.         EndGame
  396.         LineWrite
  397.         QueryUser
  398.  
  399.       Procedure ABORTGAME(limit : byte)
  400.         AbortGame can be called if the user's screen size is not large
  401.         for the game to be played.
  402.  
  403.       Procedure ENDGAME(gamename,playstr,regstr,hoffile : string;
  404.           isreg,isvalid,iscash,gethigh : boolean)
  405.  
  406.         gamename - name of the current door
  407.         playstr  - gameplayer designation (Player,Trader,etc...)
  408.         regstr   - name of BBS (registered only)
  409.         hoffile  - path and name for Text Hall of Fame
  410.         isreg    - registered game indicator
  411.         isvalid  - player's score is eligible for Hall of Fame
  412.         iscash   - player's score is in dollars (false : points)
  413.         gethigh  - higher scores are better
  414.  
  415.         EndGame is my standard Hall of Fame handling routine.
  416.  
  417.       Procedure LINEWRITE(lstr : string; lcheck : boolean)
  418.         lstr   - menu selection
  419.         lcheck - highlight selection indicator
  420.  
  421.         LineWrite is one of my basic Line Menu procedures.
  422.  
  423.       Procedure QUERYUSER
  424.         QueryUser is used to select Color or Monochrome screens.
  425.         See PortColor (Unit IOLIB).
  426.  
  427.       Function WRITECOPY(gamename,version,regnum,regstr,homestr : string;
  428.           isreg,ishome,askq : boolean) : boolean
  429.  
  430.         gamename - name of current game
  431.         version  - version of current game
  432.         regnum   - regisration number of current game
  433.         regstr   - name of BBS
  434.         homestr  - name of at home version of game
  435.         isreg    - registered game indicator
  436.         ishome   - at home version of game exists indicator
  437.         askq     - check for Instructions request indicator
  438.  
  439.         WriteCopy writes the copyrights to the screen, and optionally
  440.         questions the user to whether or not they want instructions.
  441.  
  442.  
  443.     BOI Documentation Files
  444.       BBSInfo.Doc
  445.         This is a generic information file.
  446.  
  447.       BBSNotes.Doc
  448.         This is the most complete of the documentation files, and I
  449.         recommend that it goes out with each door using a complete
  450.         and un-altered version of the BOI.
  451.  
  452.       Register.Doc
  453.         This is the registration file I include with each of my doors.
  454.  
  455.  
  456.     Future Enhancements
  457.       The windowing routines will be enhanced in the next version.
  458.       ClrPortScr will be cognizant of the actual window dimensions.
  459.       WhereX and WhereY will be fully implemented.
  460.       Procedural definition of various limits (e.g. time-out) will
  461.       be added.
  462.       More specific character input routines will be added.
  463.       All good ideas submitted will be duly considered.
  464.       A Turbo C or Turbo C++ version will be available in 1991.
  465.       A Turbo Pascal 6.0 version will also be available in early 1991.
  466.  
  467.  
  468.     Implementation Discussion
  469.       This section will be greatly enhanced in the future.  Enclosed
  470.       is a sample game that utilizes the base structure that I use
  471.       with all of my games.  The game is Hi-Lo (HILO.PAS).
  472.  
  473. END BOI Reference Manual